Pay attention! Admonitions in Hugo!

An admonition is, according to the dictionary, a firm warning or reprimand. But in documentation and the programming world, they are less threatening - they are just some boxes with warnings, info or an aside.

I have created my own admonitions for use on this site. It is very minimal, and my opinion, very cool. See the very cool one below:

Hej

Hej med dig!

In Hugo, articles (like this one) are typically written in the Markdown language. This means you cannot just enter arbitrary HTML and CSS to get something that looks like the above. However, one of the prominent Hugo features is the shortcode, a keyword in the markdown file, that when invoked, generates some arbitrary HTML. The shortcode for my admonition is seen below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<div class='admonition admonition-{{ .Get "color" }}'>
    <div>
        <img src='/img/admonition/{{ .Get "icon" }}' class='admonition-icon' alt='{{ .Get "title" }}' />
        <span class="admonition-title">{{ .Get "title" }}<span>
    </div>
    <div class="admonition-content">
        {{- if .Get "content" -}}
            {{ .Get "content" | markdownify }}
        {{- else -}}
            {{- .Inner | markdownify -}}
        {{- end -}}
    </div>
</div>

Anyone familiar with HTML will see this and think “ew, he butchered it”. The litter of {{ }} elements you see, are Go templates, that lets you, amongst other things, take arguments to the template. For example, the admonition above is produced by the following code:

{{`< admonition title="Hej" color="yellow" icon="smiley.png" >}}
Hej med dig!
{{`< /admonition >}}

Note

In the above example, I had to insert a stray backtick [ ` ] to prevent Hugo from expanding my shortcode.

On top of this, I have made a SASS (a pre-processor for CSS) file to style the admonitions. This is what gives it color, background color, mono font and scales the icon. I don’t want to gatekeep how I styled the elements, but it takes up some space, so I just suggest you inspect the stylesheet of this page.

The shortcode is very flexible, being able to use any title, any color (if defined in the .scss file) and any icon. See below:

Sigmund

The elder of a pair of brothers who came for the Orb. No one knows what Sigmund saw in the dungeon to drive him mad, but his shrewd magical tactics and wicked scythe now leave little time for his victims to wonder. Despite his reputation as a vicious murderer, his grandiose and dramatic ways have earned him the admiration of many denizens of the dungeon.

Dave

I am afraid I can’t do that Dave…

Ants!

Ants have been discovered inside your computer. Do not turn off the computer. Do not interact with the ants. If you see any ants, look away. There are no ants inside your computer. Turn off the computer now.